Class PubSubClient
Description
Defines a class of MQTT implementation for Ameba.
Syntax
class PubSubClient
Members
Public Constructors |
|
---|---|
PubSubClient::PubSubClient |
Constructs a PubSubClient object |
Public Methods |
|
---|---|
PubSubClient::setServer |
Set MQTT server address and port |
PubSubClient::setCallback |
Set callback function |
PubSubClient::setClient |
Set WiFi client |
PubSubClient::setStream |
Set data stream |
PubSubClient::connect |
Attempt to connect to server |
PubSubClient::disconnect |
Disconnect from current session |
PubSubClient::publish |
Publish a message to server |
PubSubClient::publish_P |
Same as above |
PubSubClient::subscribe |
Subscribe to a topic |
PubSubClient::unsubscribe |
Unsubscribe to a topic |
PubSubClient::loop |
Keep MQTT session alive and process any queuing tasks |
PubSubClient::connected |
Check if client still connected |
PubSubClient::state |
Return connection state |
- PubSubClient::PubSubClient
Description
Constructs a PubSubClient object and, if applicable, sets server address, port, callback function, data stream and wifi client.
Syntax
PubSubClient::PubSubClient();
PubSubClient::PubSubClient(Client& client);
PubSubClient::PubSubClient(IPAddress, uint16_t, Client& client);
PubSubClient::PubSubClient(IPAddress, uint16_t, Client& client, Stream&);
PubSubClient::PubSubClient(IPAddress, uint16_t, MQTT_CALLBACK_SIGNATURE, Client& client);
PubSubClient::PubSubClient(IPAddress, uint16_t,MQTT_CALLBACK_SIGNATURE, Client& client, Stream&);
PubSubClient::PubSubClient(uint8_t*, uint16_t, Client& client);
PubSubClient::PubSubClient(uint8_t*, uint16_t, Client& client, Stream&);
PubSubClient::PubSubClient(uint8_t*, uint16_t, MQTT_CALLBACK_SIGNATURE, Client& client);
PubSubClient::PubSubClient(uint8_t*, uint16_t,MQTT_CALLBACK_SIGNATURE, Client& client, Stream&);
PubSubClient::PubSubClient(const char*, uint16_t, Client& client);
PubSubClient::PubSubClient(const char*, uint16_t, Client& client, Stream&);
PubSubClient::PubSubClient(const char*, uint16_t, MQTT_CALLBACK_SIGNATURE, Client& client);
PubSubClient::PubSubClient(const char*, uint16_t, MQTT_CALLBACK_SIGNATURE, Client& client, Stream&);
Parameters
client
: the network client to use, for example WiFiClient
IPAddress
: MQTT server address
port
: port for MQTT, usually 1883 for unencrypted connection
MQTT_CALLBACK_SIGNATURE
: callback function for MQTT
Stream
: a stream to write received messages to
Returns
The function returns nothing.
Example Code
Example: MQTT_Basic
Notes and Warnings
PubSubClient::PubSubClient(Client& client) would suffice for normal MQTT connection
- PubSubClient::setServer
Description
Sets the server details.
Syntax
PubSubClient& PubSubClient::setServer(uint8_t * ip, uint16_t port)
PubSubClient& PubSubClient::setServer(IPAddress ip, uint16_t port)
PubSubClient& PubSubClient::setServer(const char* domain, uint16_t
port)
Parameters
ip
: the address of the server
port
: the port to connect to, default 1883
domain
: the address of the server
Returns
The client instance, allowing the function to be chained
Example Code
Example: MQTT_Basic
Notes and Warnings
NA
- PubSubClient::setCallback
Description
Sets the message callback function.
Syntax
PubSubClient& PubSubClient::setCallback(MQTT_CALLBACK_SIGNATURE)
Parameters
MQTT_CALLBACK_SIGNATURE
: a pointer to a message callback function
called when a message arrives for a subscription created by this
client.
Returns
The client instance, allowing the function to be chained.
Example Code
Example: MQTT_Basic
Notes and Warnings
NA
- PubSubClient::setClient
Description
Sets the network client instance to use.
Syntax
PubSubClient& PubSubClient::setClient(Client& client)
Parameters
client
: the network client to use, for example WiFiClient
Returns
The client instance, allowing the function to be chained
Example Code
NA
Notes and Warnings
NA
- PubSubClient::setStream
Description
Sets the stream to write received messages to.
Syntax
PubSubClient& PubSubClient::setStream(Stream& stream)
Parameters
stream
: a stream to write received messages to
Returns
The client instance, allowing the function to be chained.
Example Code
NA
Notes and Warnings
NA
- PubSubClient::connect
Description
Connects the client to the server.
Syntax
boolean PubSubClient::connect(const char *id)
boolean PubSubClient::connect(const char *id, const char *user, const char *pass)
boolean PubSubClient::connect(const char *id, const char* willTopic, uint8_t willQos, boolean willRetain, const char* willMessage)
boolean PubSubClient::connect(const char *id, const char *user, const char *pass, const char* willTopic, uint8_t willQos, boolean willRetain, const char* willMessage)
Parameters
id
: Client ID, a unique string identifier
user
: Username for authentication, default NULL
pass
: Password for authentication, default NULL
willTopic
: the topic to be used by the will message
willQoS
: the quality of service to be used by the will message
willRetain
: whether the will should be published with the retain flag
willMessage
: the payload of the will message
Returns
True – connection succeeded
False – connection failed
Example Code
Example: MQTT_Basic
Notes and Warnings
Client ID is required and should always be unique else connection might be rejected by the server.
- PubSubClient::disconnect
Description
Disconnect the client
Syntax
void PubSubClient::disconnect(void)
Parameters
The function requires no input parameter.
Returns
The function returns nothing.
Example Code
NA
Notes and Warnings
NA
- PubSubClient::publish
Description
Publishes a message to the specified topic.
Syntax
boolean PubSubClient::publish(const char* topic, const char* payload)
boolean PubSubClient::publish(const char* topic, const char* payload, boolean retained)
boolean PubSubClient::publish(const char* topic, const uint8_t* payload, unsigned int plength)
boolean PubSubClient::publish(const char* topic, const uint8_t* payload, unsigned int plength, boolean retained)
Parameters
topic
: the topic to publish to
payload
: the message to publish
plength
: the length of the payload. Required if payload is a byte[]
retained
: whether the message should be retained
– false – not retained
– true – retained
Returns
False – publish failed, either connection lost or message too large
True – publish succeeded
Example Code
Example: MQTT_Basic
Notes and Warnings
Default max packet size is 128 bytes.
- PubSubClient::publish_P
Description
Publishes a message stored in PROGMEM to the specified topic.
Syntax
boolean PubSubClient::publish_P(const char* topic, const uint8_t* payload, unsigned int plength, boolean retained)
Parameters
topic
: the topic to publish to
payload
: the message to publish
plength
: the length of the payload. Required if payload is a byte[]
retained
: whether the message should be retained
– false – not retained
– true – retained
Returns
False – publish failed, either connection lost or message too large
True – publish succeeded
Example Code
NA
Notes and Warnings
NA
- PubSubClient::subscribe
Description
Subscribes to messages published to the specified topic.
Syntax
boolean PubSubClient::subscribe(const char* topic)
boolean PubSubClient::subscribe(const char* topic, uint8_t qos)
Parameters
topic
: the topic to subscribe to
qos
: the qos to subscribe at
Returns
False – sending the subscribe failed, either connection lost or message too large
True – sending the subscribe succeeded
Example Code
Example: MQTT_Basic
Notes and Warnings
NA
- PubSubClient::unsubscribe
Description
Unsubscribes from the specified topic.
Syntax
boolean PubSubClient::unsubscribe(const char* topic)
Parameters
topic
: the topic to unsubscribe to
Returns
False – sending the unsubscribe failed, either connection lost or message too large
True – sending the unsubscribe succeeded
Example Code
NA
Notes and Warnings
NA
- PubSubClient::loop
Description
A must method called regularly to allow the client to process incoming messages and maintain its connection to the server.
Syntax
boolean PubSubClient::loop(void)
Parameters
The function requires no input parameter.
Returns
False – the client is no longer connected
True – the client is still connected
Example Code
Example: MQTT_Basic
Notes and Warnings
A required method that should not be blocked for too long.
- PubSubClient::connected
Description
Checks whether the client is connected to the server.
Syntax
boolean PubSubClient::connected(void)
Parameters
The function requires no input parameter.
Returns
False – the client is not connected
True – the client is connected
Example Code
Example: MQTT_Basic
Notes and Warnings
NA
- PubSubClient::state
Description
Returns the current state of the client. If a connection attempt fails, this can be used to get more information about the failure. All of the values have corresponding constants defined in PubSubClient.h.
Syntax
int PubSubClient::state(void)
Parameters
The function requires no input parameter.
Returns
-4 : MQTT_CONNECTION_TIMEOUT – the server didn’t respond within the
keepalive time
-3 : MQTT_CONNECTION_LOST – the network connection was broken
-2 : MQTT_CONNECT_FAILED – the network connection failed
-1 : MQTT_DISCONNECTED – the client is disconnected cleanly
0 : MQTT_CONNECTED – the client is connected
1 : MQTT_CONNECT_BAD_PROTOCOL – the server doesn’t support the requested version of MQTT
2 : MQTT_CONNECT_BAD_CLIENT_ID – the server rejected the client identifier
3 : MQTT_CONNECT_UNAVAILABLE – the server was unable to accept the connection
4 : MQTT_CONNECT_BAD_CREDENTIALS – the username/password were rejected
5 : MQTT_CONNECT_UNAUTHORIZED – the client was not authorized to connect
Example Code
Example: MQTT_Basic
Notes and Warnings
NA